fix(create-objectstack): install the skills bundle for one agent so a scaffolded project commits it once - #16401

Fixes #16331

Route B, chosen on measurement

The card offered two routes and made the choice an in-card decision. Route B — install for one agent runtime by default and print the one-liner for the others — was taken, and every alternative was built and cloned rather than argued about.

Measured against skills@1.5.23 and this repo's 11-skill catalog, each into an empty directory:

Then, with the template's .gitignore in place, git init && git add -A && git commit, then git clone into a clean directory:

Route A's naive shape is the trap the triage comment predicted, and it is reproduced above by actually cloning, not by reasoning. Route A's viable shape does satisfy the card's acceptance on POSIX, and it was rejected for two reasons: it commits symlinks that git-for-Windows' default checkout materialises as stray text files, and — the structural one — a _gitignore deny-list is the wrong shape regardless of which paths it names. This package does not choose the destination set; the skills CLI does, and it moves with that package's releases. created-summary.ts already documents the same property for the same reason. An ignore list has to chase it silently, in the direction that re-commits duplicates. Naming our own destination is explicit composition instead of default magic.

The cost is the multi-runtime default, and it is paid in the open (see the new closing block below).

Acceptance, verified end to end

A real scaffold with the real skills CLI (only the package manager was stubbed; an install is irrelevant to the skills bundle), then git add -A, commit, and git clone into a clean directory:

staged total          : 62
staged SKILL.md paths : 11
staged symlinks       : 0
untracked after add   : 0
staged roots          : .claude .dockerignore .github .gitignore AGENTS.md Dockerfile
                        README.md docker-compose.yml objectstack.config.ts
                        objectstack.manifest.json package.json pnpm-workspace.yaml
                        skills-lock.json src tsconfig.json

CLONE into a clean directory
  cloned SKILL.md files : 11
  dangling symlinks     : 0
  .claude/ total        : 604,102 bytes
  ./.claude/skills/objectstack-ai/SKILL.md        21,866 bytes
  ./.claude/skills/objectstack-api/SKILL.md       18,535 bytes
  ./.claude/skills/objectstack-automation/SKILL.md 50,043 bytes

No .agents/, no agent/, nothing left untracked.

What changed

• src/skills-install.ts (new) — one source for the command. The scaffolder runs it and the closing summary prints the same builder's output with a different agent name; a drifted pair is how a project acquires the second copy. The header carries the measurement table above.
• src/index.ts — runs SKILLS_INSTALL_COMMAND; the closing summary now prints an AI Skills block on every path, not only the skipped one. A single-agent install leaves every other runtime uninstalled, and an absent capability has to say so with the remedy:

    AI Skills:
      Installed for claude-code → .claude/skills/ — commit it with your project.
      Using a different agent? Add it one runtime at a time:
        npx skills add objectstack-ai/objectstack/skills --skill '*' --agent codex -y
        (`npx skills add --help` lists every agent name)
  

• src/scaffold-skills-single-copy.test.ts (new) — the acceptance assertion the card asked for, counting staged SKILL.md paths. It runs the real CLI through tsx under a stubbed PATH; the skills CLI is stubbed from the measured destination map, and the stub refuses an argv it has no measured row for (exit 3) so a command nobody measured fails loudly instead of passing against an invented layout. A vacuity block replays the --all row and requires the same assertions to fail.
• src/template-consistency.test.ts — the /skills subpath boundary is unchanged and still enforced; the pin now asserts the value the scaffolder runs rather than the source text that happens to hold it, and a second case keeps a hand-written duplicate invocation from creeping back in.
• src/created-summary.ts, README.md, src/templates/AGENTS.md, src/templates/blank/README.md — prose. The two template files told a project's future readers to run the bare interactive form; picking "all" there re-creates the triplicate inside the user's own repository, so both now name the per-agent form and refuse --all with the reason.
• Changeset: create-objectstack minor — Route B changes what gets installed, per the card.

_gitignore is deliberately unchanged: with one destination there is nothing to exclude, and a deny-list for directories we no longer create is dead text.

Verification

• pnpm --filter create-objectstack test — 16 files, 203 passed. typecheck clean, and tsc --listFiles confirms both new files are in the program (a typecheck that misses the test files is not coverage).
• Ablation (from a committed implementation, on-disk mutation proved by blob hash, restored and re-verified against the HEAD blob): reverting SKILLS_INSTALL_COMMAND to --all turns 9 of 14 cases red, with the defect's own signature — staged roots ['.agents','agent'], 6 staged SKILL.md instead of 3, 3 symlinks. Restore leg: git diff HEAD empty, blob hash identical to HEAD.
• Gates: node scripts/pm/dispatch-gates.mjs --ran reports 55 derived families, 55 run, 0 NOT-MEASURED, 0 UNRUN — including the two template families this path set pulls in (check:template-manifests, check:template-version-sync) and check:published-files.
• pnpm lint — the full repo-wide eslint . --no-inline-config, exit 0 in 100s at 604dc4d2. Not a narrowing.
• packages/cli is in turbo ls --affected (it declares create-objectstack as a dependency): closure built, --project unit green — 181 files, 2438 passed. The other six affected packages reach this diff only through the one published entry point, create-objectstack/created-summary, and that entry point is byte-identical across the diff (dist/created-summary.js and .d.ts sha256 unchanged when the file is reverted to origin/main and rebuilt).

Three gate results needed a note rather than a re-run: check:dual-build-cjs-loads and check:type-check-debt first answered PREREQUISITE NOT MET (exit 3) because the workspace closure was unbuilt — both green once it was built. check:type-check-debt then OOM'd under the container's default --max-old-space-size=4096, which is tighter than the 6144 ceiling the gate pins for itself; green at its own ceiling. check-plugin-teardown-shape --self-test could not reach its pinned fixture commit on a shallow checkout, and is green after git fetch origin 621a4876.

Out of scope, filed

#16400 — five documentation surfaces still tell readers to install with --all, and two of them describe what the scaffolder does, so they go stale with this PR. content/docs/** and skills/** are outside this card's file surface and pull in a different gate family (skills/** is governed). Following those instructions in a git repository reproduces the triplication independently of the scaffolder, so closing this card does not close that.

Not touched, per the card: the CI workflow (#16330, landed as 4998efa7), packages/cli/src/commands/init.ts (#16350), the scaffolded-project SyntaxError (#16373), and content/docs/releases/**.

Generated by Claude Code